Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
ODRefCntCollection is a utility providing a collection (ordered list) that contains instances of ODRefCntObject. The interface is intentionally similar to another OpenDoc utility, OrderedCollection, which also provides the bulk of the implementation. ODRefCntCollection is intended to be a replacement for OrderedCollection when the elements are reference counted.
There are two reasons why using ODRefCntCollection instead of OrderedCollection is a good idea. First, it is difficult for OpenDoc clients to ref-count objects correctly without taking a strictly formal approach to acquiring and releasing objects in a balanced fashion. Using ODRefCntCollection, objects are acquired when the enter the collection and released if and only if elements are explicitly removed or the collection is destroyed. (The RemoveFirst(), RemoveLast(), and Remove() methods are exceptions, in that they do not release, because presumably the client intends to use the object removed before releasing it.) This maintains the simple invariant that an object in the collection has one extra reference when it is in the collection. The second reason is to reduce code size; calls to acquire or release occur inside the collection and not every place that objects are either added to or removed from the collection.
While OrderedCollection was designed to be subclassed, ODRefCntCollection was not. ODRefCntCollection uses a subclass of OrderedCollection named ODObjectOrdColl, which knows that reference counted objects must be compared for equality using ODObjectsAreEqual(), and overrides ODObjectOrdColl::ElementsMatch() to do this. ODRefCntCollection has (not is) an instance of ODObjectOrdColl, and many ODRefCntCollection methods are implemented as non-virtual inline calls to appropriate OrderedCollection methods.
The iterator for ODRefCntCollection is named ODRefCntCollectionIterator. The implementation of ODRefCntCollectionIterator delegates all operations to OrderedCollectionIterator. Clients are expected to create instances of ODRefCntCollectionIterator on the stack, although nothing stops clients from creating them in the heap if desired. However, note that there is no CreateIterator() method defined on the collection class encouraging clients to place iterators pointlessly in the heap.
Both constructors save the environment for use in making reference count calls on objects in the collection, so methods that make such calls do not need an environment argument. (The motivation was to support releasing in the destructor which needs the environment but cannot pass one in.) The collection allocates memory in the heap specified by where, or else in the default heap if not provided.
ODRefCntCollection::~ODRefCntCollection();
Removes and releases every objects in the collection.
Adds element to the back of the ordered collection, and then acquires element.
void ODRefCntCollection::AddBeforeAndAcquire(
ODRefCntObject* existing,
ODRefCntObject* tobeadded);
Adds tobeadded in front of existing, and then acquires tobeadded. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
void ODRefCntCollection::AddAfterAndAcquire(
ODRefCntObject* existing,
ODRefCntObject* tobeadded);
Adds tobeadded in back of existing, and then acquires tobeadded. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
Returns the object after existing in the collection, or null if there is no object after existing. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
Returns the object before existing in the collection, or null if there is no object before existing. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
Removes and returns the first object in the collection, or null if there are no objects in the collection. An object so removed is not released, and clients must eventually release it. The object is not released because presumably clients want to use it, because the first element in particular was requested.
ODRefCntObject* ODRefCntCollection::RemoveLast();
Removes and returns the last object in the collection, or null if there are no objects in the collection. An object so removed is not released, and clients must eventually release it. The object is not released because presumably clients want to use it, because the last element in particular was requested.
void ODRefCntCollection::RemoveAndReleaseAll();
Removes and releases every object in the collection.
Removes existing if it was in the collection, returning true if existing was in the collection or false if it was not in the collection. existing is not released, and clients must eventually release existing if it was in the collection. (Use RemoveAndRelease() if you want it both removed and released.) Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
Removes existing if it was in the collection, returning true if existing was in the collection or false if it was not in the collection.
existing is released if and only if it was in the collection. If the collection had the last reference to existing, then clients must not make any more calls on existing after it is released. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
Returns whether existing is currently in the collection. Note that ODObjectsAreEqual() is used as the test for equality between existing and elements in the collection.
ODMemoryHeapID GetHeap() const;
Return the heap in which the collection allocates memory.
